ASME's Mechanical Engineering Toolkit 1997 December

home *** CD-ROM | disk | FTP | other *** search

/ ASME's Mechanical Engine…ing Toolkit 1997 December / ASME's Mechanical Engineering Toolkit 1997 December.iso / edu_comp / lim-40.lzh / EMS-40.TXT

Wrap

Text File | 1987-09-18 | 40.9 KB | 1,185 lines

A Comparison of EMS 4.0 with EMS and EEMS 3.2 Report by Stephen T. Satchell Revision B, September 17, 1987 ____________________________________________________________ Copyright 1987 Satchell Evaluations. Permission is granted to all persons to freely duplicate and distribute this information with the following restrictions: (1) This document is transferred unmofigirf, with all notices in place. (2) No fee may be directly or indirectly charged for this information EXCEPT by (a) on-line services and bulletin board systems that charge for access so long as no surcharge applied to this file, and (b) by professional computer societies (ACM, IEEE Computer and the like) which regularly publish a journal or magazine. User groups and for-profit groups are specifically prohibited from selling media (paper or machine readable) containing this information. Permission for other uses may be requested from Satchell Evaluations, 16 Searing Avenue, Morristown NJ 07960. The author asks that people using any exerpt from this report contact him to insure the information is accurate to the author's best knowledge before publication. This document is the result of the author's own initiative, and is not work for hire. This work is derived from three published documents: (1) _The Lotus/Intel/Microsoft Expanded Memory Specification_ Version 3.20 September 1985, (2) _Enhanced Expanded Memory Specification Version 3.20 June 1986, and (3) _Lotus/Intel/Microsoft Expanded Memory Specification_ Version 4.0 August 1987 (final printed version) The prior revision of this document was based on a laser printed manuscript. Another document mentioned here is the _Generic Accelerator Card Driver (GACD) Specification_ available from AST Research Inc. Intel is a trademark of Intel Corporation. Lotus is a trademark of Lotus Development Corporation. Microsoft is a trademark of Microsoft Corporation. ____________________________________________________________ Preface to Revision B: ---------------------- The original version of this document was based on the EMS 4.0 specification handed out to the press at the August 19th announcement. Since then, Intel informed the author that this copy of the specification was preliminary and contained several errors that are corrected in the final printed version of the specification. Unfortunately, both documents carry the same version, part number and date. The ONLY difference is that the correct document is in the 5x8.5 format, while the document containing errors is 8.5x11. The original of this document was in two pieces: the comparision and a separate error/problem sheet. These two pieces are now combined into the single document as the elimination of the typos "correct" the problems found. Programmers are urged to consider that some of the driver implementers are human, and might read things into the specification that simply are not true. IN SHORT, WATCH OUT FOR BOUNDARY VIOLATIONS BY ENHANCED MEMORY MANAGERS. The author understands the difference between physical and logical pages, but in some parts of the prior version of this document the author got mixed up and swapped terms. This has been corrected. A physical page is a 16 KB location in the 1 MB address space of the 80x86 system, while a logical page is a block of RAM that can be mapped into a physical page. 'Nuff said. Sorry. The section on limits has been expanded considerably, based on documents from both Intel and AST. Other sections have been expanded as well, including minor corrections. Buried in the back of the specification, this statement appears: ``To support generic accelerator cards, the support of Function 34, as defined by AST, is encouraged.'' Unfortunately, all copies of the AST EEMS specification in my posession do not have any concrete description of this function, and Intel didn't include this information. Interested persons should contact AST and ask for a copy of the _Generic Accelerator Card Driver (GACD) Specification_. I will attempt to obtain a copy of this and include the information in a future revision of this document. ____________________________________________________________ INTRODUCTION ------------ On August 19, 1987, the new version of the Expanded Memory Specification (EMS) was announced by Lotus, Intel and Microsoft. This new version of the specification includes many features of the Enhanced Expanded Memory Specification (EEMS) originally developed by AST Reserach, Quadram and Ashton-Tate, although the three original sponsoring companies elected not to make the new specification upward compatible with EEMS. AST Research indicated in a separate statement that they would endorse EMS 4.0 without reservation. An important aside unrelated to this document is that Lotus Development Corporation has stated that pure software implementations of EMS 4.0 (those that do not use either dedicated memory hardware, PS/2 T-RAM or 80386 page mapping) will not be supported by Lotus products. This paper attempts to compare EMS 4.0 with both EMS 3.2 and EEMS 3.2 specifications, by looking at each function. This is not intended to republish the specification -- interested parties are urged to contact Intel Corporation at (800) 538-3373 and ask for the "EMS 4.0 Developers Kit". The functions will be listed by hexidemical code, not by abstract function number. This is of more use to developers since they tend to think of the functions based on the value loaded into the registers, not by an index. Where subfunctions are defined (such as in function 4Eh "Page Map Functions" the function and subfunction will be separated by a slash. Within the body of the text, I will indicate whether the EMS 4.0 function is upwardly compatible with the older specifications. This document can also serve as a quick reference to those programmers already familiar with the EMS 4.0 specification and wanting a synopsis of the calling sequences for EMS operations. Programmers and interested parties wishing to fully understand the implications of each function is urged to examine the Base Document, _Lotus/Intel/Microsoft Expanded Memory Specification_ Version 4.0, available from Intel by calling (800) 538-3373 and asking for the EMS 4.0 Developers Kit. MAJOR DIFFERENCES ----------------- One significant change is that the total amount of memory managed by an Expanded Memory Manager (EMM) has grown from 8 megabytes to "full-tilt-boogy" 32 megabytes (to quote a recent _InfoWorld_ article) -- 512 pages to 2048 pages of 16 KB each. In this author's opinion, there is no reason a programmer should assume this is the absolute limit. THAT is dictated by the use of 16 bit signed values for page numbers, capping capacity at 32768 pages of 16 KB each -- 512 megabytes of RAM. Programs can interrogate the EMM for the actual amount available and tailor operations accordingly. Note the developers do not indicate whether the word values used for pages are signed or unsigned. If the values are intended to be unsigned, then 65535 (with page value FFFFh treated as a special value) can exist, or 16 KB short of one gigabyte of RAM in a single system. DEFINITION OF LIMITS -------------------- This is the worst part of the specification, since in no single place does the spec writers completely list the assumptions about limits, let alone future directions concerning those limits. Here is the author's ideas of the limits that drive the specification. Where possible the author has erred toward the more inclusive. Maximum RAM: 32 MB today, future 512 MB Minimum number of logical pages: 4 (64 KB). Maximum number of logical pages: 2048 today, future 32768. Minimum number of physical pages: 4 (64 KB). Maximum number of physical pages: 64 (full 1 MB space). Minimum number of handles: 64 (includes OS handle 00h). Maximum number of handles: 255 (includes OS handle 00h). Minimum # EMS 3.2 page maps: one per handle Maximum # EMS 3.2 page maps: unbounded Maximum size of mem reg array: 254 bytes The "page maps" refer to contexts saved by functions 47h and 48h, Save Page Map and Restore Page Map. The number of logical pages in a particular system can be obtained using function 42h; this also has the useful side effect of telling you the number of free pages as well. The number of physical pages in a particular system can be obtained by using function 58h/01h and the particular mapping by using function 58h/00h. Should this function fail, you can assume you have four pages starting at the segment returned by function 41h. The maximum number of handles that can be defined is 255. For those implementations that do not do any mapping in conventional memory, you can have 255 user handles. For those implementations that map into conventional memory, you can have 254 user handles and the special operating system handle. Note that handle values can range from 01h to FFh in the first case, or from 00h to FEh in the second. The maximum number of handles in a particular system can be obtained by using function 54h/02h. Should this function fail, you can make no assumptions about the number of handles available. GOTCHAS ------- This section is what was left from the errata file in the prior version. If you prefer to work with possibly incorrect implementations of the EMS specification, pay particular heed to the comments here, as they can save you untold grief when you (and other programs in a system) stretch an expanded memory manager to the limit and beyond. The author makes NO claim that he has found all of these; if you discover another, please let the author know so he can add your new gotcha to the next revision (and you will receive credit for your contribution). 46h -- Get Version [7] === There exists some confusion whether the version returned is the specification supported or the version number of the driver. Programmers are united in stating this should be the specification version supported, while at least one vendor (Intel) is known to use this function to return the software version of the particular implementation. The wording of the description indicates that the vendor revision is intended, and thus is useless to programmers wishing to be able to adapt to the environment they encounter. The author considers this a severe weakness in the specification. Either a different function should be provided for returning vendor specific version information or other means for obtaining the current implementation version should be provided and documented by each vendor. Function 4Dh, Get All Handles [14] ============ BX is specified to have a maximum value of 255. A non-conforming implementation could indeed allow 256 handles, assuming that since handles can range in value from 00h to FFh that the full range should be implemented. Consider allowing for 256 entries in the array instead of the 255 entries as indicated in the example for this function. There is also a problem with identifying the difference between a raw handle and a standard handle. Currently there is no facility to make this determination. Obviously the program making the allocation needs to keep this straight, but another program happening onto a raw handle (such as a debug program) has no way of really knowing. Unfortunate oversight, especially since the specification makes no comment about whether the page count is EMS pages, raw pages, or a funny number. Function 54h Subfunction 00h, Get Handle Directory [21/0] ============ Consider allow for 256 names in the handle directory array instead of 255 should a particular implementation violate the limit set up in the specification. Function 56h Subfunctions 00h/01h, Alter Page Map and Call [23] ============ The function description indicates that register and flag contents (except for AX) are preserved going to the called function. This means that BX, CX, DI, and ES are available for passing values to the called function. Although not explicit, the flags and all registers EXCEPT AX are unmodified when returning from the remotely called function. Since many compilers use AX to return integer values from functions, there needs to be examples showing how to preserve the value when making EMS calls. This may indeed require direct compiler support...something that will not happen overnight. The specification does not indicate whether the EMM handle passed in DX must describe pages contained by both calling and called routines, or whether there can be two different handles involved as well. MISSING ======= A function to return the current logical->physical mapping in a vendor-independent manner. This would be exceedingly useful in debuggers. FUNCTIONS DEFINED IN EMS 3.2 SPECIFICATION ------------------------------------------ 40h -- Get Status [1] === On call: AH = 40h On return: AH = error status Error Status: 00h, 80h, 81h, 84h Upward and downward compatible with both EMS and EEMS 3.2. 41h -- Get Page Frame Segment Address [2] === On call: AH = 41h On return: AH = error status BX = page frame segment address Error Status: 00h, 80h, 81h, 84h Upward and downward compatible with both EMS and EEMS 3.2. 42h -- Get Unallocated Page Count [3] === On call: AH = 42h On return: AH = error status BX = number of unallocated pages DX = number of total pages Error Status: 00h, 80h, 81h, 84h Upward and downward compatible with both EMS and EEMS 3.2. Note that EMS and EEMS 3.2 had no mechanism to return the maximum number of handles that can be allocated by programs. This is handled by the EMS 4.0 new function 54h/02h. 43h -- Allocate Pages [4] === On call: AH = 43h BX = number of 16 KB pages requested (zero OK) On return: AH = error status DX = handle Error Status: 00h, 80h, 81h, 84h, 85h, 87h, 88h Upward compatible with both EMS and EEMS 3.2; EMS and EEMS 3.2 do not allow the allocation of zero pages (returns error status 89h). EMS 4.0 does allow zero pages to be requested for a handle, allocating pages later using function 51h, Reallocate Pages. 44h -- Map/Unmap Handle Page [5] === On call: AH = 44h AL = physical page to be mapped BX = logical page to be mapped (-1 to unmap) DX = handle On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ah, 8Bh Upward compatible with both EMS and EEMS 3.2; EMS and EEMS 3.2 do not support unmap (logical page FFFFh) capability. Also, E/EMS 3.2 specified there were precisely four physical pages; EMS 4.0 uses the subfunctions of function 58h to return the permitted number of physical pages. This incorporates the functionality of function 69h ("function 42") of EEMS. 45h -- Deallocate Pages [6] === On call: AH = 45h DX = handle On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 86h Upward and downward compatible with both EMS and EEMS 3.2. 46h -- Get Version [7] === On call: AH = 46h On return: AH = error status AL = version number Error Status: 00h, 80h, 81h, 84h Upward and downward compatible with both EMS and EEMS 3.2. See the GOTCHA section for a discussion about a problem with this function. It appears that the intended use for this function is to return the version of the vendor implementation of the expanded memory manager instead of the specification version. In short, this function is useless to the vendor-independant programmer as defined. 47h -- Save Page Map [8] === On call: AH = 47h DX = caller's EMM handle (NOT current EMM handle) On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ch, 8Dh Upward and downward compatible with both EMS and EEMS 3.2. This only saves the context saved in EMS 3.2 specification; if a driver, interrupt routine or TSR needs to do more, functions 4Eh (Page Map functions) or 4Fh (Partial Page Map functions) should be used. The specification is silent about the number of save contexts to provide. AST recommends in their Rampage AT manual one save context for each handle plus one per possible interrupt (5 + <handles>). In the LIMITS section of the document the minimum number of save contexts is the number of handles. 48h -- Restore Page Map [9] === On call: AH = 48h DX = caller's EMM handle (NOT current EMM handle) On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Eh Upward and downward compatible with both EMS and EEMS 3.2. This only restores the context saved in EMS 3.2 specification; if a driver, interrupt routine or TSR needs to do more, functions 4Eh (Page Map functions) or 4Fh (Partial Page Map functions) should be used. 49h -- (reserved) [10] === This function formerly returned the page mapping register I/O port array. Use of this function is discouraged, and in EMS 4.0 may conflict with the use of the new functions (4Fh through 5Dh). 4Ah -- (reserved) [11] === This function formerly returned the page translation array. Use of this function is discouraged, and in EMS 4.0 may conflict with the use of the new functions (4Fh through 5Dh). It is odd that no function presents in a vendor-independent manner the current mapping of logical pages to physical pages. This would be exceedingly handy in a debugging environment (such as Periscope or CodeView) in trying to track down bugs in programs using expanded memory. 4Bh -- Get Handle Count [12] === On call: AH = 4Bh On return: AH = error status BX = handle count Error Status: 00h, 80h, 81h, 84h Upward and downward compatible with EMS and EEMS 3.2. 4Ch -- Get Handle Pages [13] === On call: AH = 4Ch DX = handle On return: AH = status BX = pages allocated to handle Error Status: 00h, 80h, 81h, 83h, 84h This function is upward compatible with EMS and EEMS 3.2. It is interesting to note how foolish the spec writers were, in that the E/EMS 3.2 spec writers state that "[the contents of BX] never exceeds 512 because the EMM allows, at most, 512 pages of expanded memory." EMS 4.0 makes a lie of this statement, yet falls into the same trap by stating that the contents of BX will never exceed 2048. DON'T BELIEVE IT. This author suspects that future versions of the spec will make the EMS 4.0 specification lie, too. The programmer should make no assumptions about the order handles appear in the array. Paranoid programmers (like the author) should compare the number returned in BX with the maximum number of pages returned by function 42h register DX, total number of EMM pages. This should be an UNSIGNED comparison, just in case the spec writers decide to use 16 bit unsigned numbers (for a maximum space of one gigabyte) instead of signed numbers (for a maximum space of 512 megabytes). Unsigned comparisons will work properly in either case, and the author recommends the use of unsigned comparisons. 4Dh -- Get All Handle Pages [14] === On call: AH = 4Dh DI = offset to 1020 byte array ES = segment selector for 1020 byte array On return: AH = error status BX = number of active handles (1-255) Error Status: 00h, 80h, 81h, 84h NOT COMPATIBLE with EMS or EEMS 3.2, since the new special OS handle 0000h is returned as part of the array. Unless benign use of this information is used (such as displaying the handle and count of pages associated with the handle) code should be changed to only work with handles between 01h and FFh and to specifically ignore handle 00h. The array consists of an array of 255 elements. The first word of each element is the handle number, the second word contains the number of pages allocated. PROBLEM: There are two types of handles, "standard" and "raw". The specification does not talk about how this function works when both raw and standard handles exist in a given system. There currently is NO way to differentiate between a standard handle and a raw handle in EMS 4.0 that the author can find. Ooops. This is particularly painful in debuggers when the hardware and EMM support raw pages whose size differs from the 16 KB standard page size. 4Eh -- Page Map Functions [15] === This group of four sub-functions are provided for context switching required by operating environments and systems. These functions are upward and downward compatible with both EMS and EEMS 3.2; in addition, these functions now include the functionality of EEMS function 6Ah ("function 43") involving all pages. The size and contents of the mag register (map reg) array will vary from system to system based on hardware vendor, software vendor, number of boards and the capacity of each board in the system. Note the array size can be determined by function 4Eh/03h. 4Eh/00h -- Get Page Map [15/0] On call: AH = 4Eh AL = 00h DI = offset to target array ES = segment selector for target array On return: AH = error status Error Status: 00h, 80h, 81h, 84h, 8Fh 4Eh/01h -- Set Page Map [15/1] On call: AH = 4Eh AL = 01h SI = offset to source array DS = segment selector for source array On return: AH = error status Error Status: 00h, 80h, 81h, 84h, 8Fh, A3h 4Eh/02h -- Get and Set Page Map [15/2] On call: AH = 4Eh AL = 02h SI = offset to source array (new context) DI = offset to target array (old context) DS = segment selector for source array ES = segment selector for target array On return: AH = error status Error Status: 00h, 80h, 81h, 84h, 8Fh, A3h 4Eh/03h -- Get Size of Page Map Save Array [15/3] On call: AH = 4Eh AL = 03h On return: AH = error status AL = size in bytes of array Error Status: 00h, 80h, 81h, 84h, 8Fh FUNCTIONS NEW TO EMS 4.0 ------------------------ 4Fh -- Partial Page Map Functions [16] === This group of four sub-functions are provided for context switching required by interrupt routines, operating environments and systems. This set of functions provides extended functionality over the EEMS function 6Ah ("function 43") involving subsets of pages. In EEMS, a subset of pages could be specified by starting position and number of pages; in this function a list of pages is specified, which need not be contiguous. Interrupt routines can use this function in place of functions 47h and 48h, especially if the interrupt routine wants to use more than the standard four physical pages. The page map is a structure of words. The first word indicate the number of pages specified. The remaining words contain the segment selector (NOT the physical page number) for each page. Translation from physical page number to segment selectors can be performed using function 58h/00h, Get Mappable Physical Address Array. The size and contents of the mag register (map reg) array will vary from system to system based on hardware vendor, software vendor, number of boards and the capacity of each board in the system. Note the array size can be determined by function 4Fh/02h. NOTE: there is no equivelant to 4Eh/02h, Get And Set, in this group of functions. From the point of view of system maintenance, the author would have preferred that subfunction 02h be reserved and the get-size command be subfunction 03h. Unfortunatly the die is cast. 4Fh/00h -- Get Partial Page Map [16/0] On call: AH = 4Fh AL = 00h SI = offset of page specification array DI = offset of target map reg array DS = segment selector of page spec array ES = segment selector of target map reg array On return: AH = error status Error Status: 00h, 80h, 81h, 84h, 8Bh, 8Fh, A3h 4Fh/01h -- Set Partial Page Map On call: AH = 4Fh AL = 01h SI = offset of source map reg array DS = segment selector of source map reg array On return: AH = error status Error Status: 00h, 80h, 81h, 84h, 8Fh, A3h 4Fh/02h -- Get Size of Partial Page Map Save Array On call: AH = 4Fh BX = number of pages in page spec array On return: AH = error status AL = size in bytes of mag reg array Error Status: 00h, 80h, 81h, 84h, 8Bh, 8Fh 50h -- Map/Unmap Multiple Pages [17/0][17/1] === On call: AH = 50h AL = 00h (by physical page) or 01h (by seg#) CX = number of mapping word pairs in array DX = handle SI = offset of source map array DS = segment selector of source map array On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ah, 8Bh, 8F New function permits multiple logical-to-physical assignments to be made in a single call. The source map array is an array of word pairs. The first word of a pair contains the logical page to map (FFFFh if the physical page is to be totally unmapped) and the second word of a pair contains the physical page number (subfunction 00h) or the segment selector (subfunction 01h) of the physical page in which the logical page shall be mapped. A map of available physical pages (by physical page number and segment selectors) can be obtained using function 58h/00h, Get Mappable Physical Address Array. 51h -- Reallocate pages [18] === On call: AH = 51h BX = number of pages desired at return DX = handle On return: AH = error status BX = number of pages now associated with handle Error Status: 00h, 80h, 81h, 83h, 84h, 87h, 88h New function which permits the number of pages associated with a handle to be decreased or increased. 52h -- Handle Attribute Functions [19] === Something new added to the EMS specification is the ability to mark a handle and pages assoicated with a handle as non-volatile -- preserved across a warm boot of the system. The specification indicates that few if any EMS systems will support such a feature since the EMS hardware must insure the data remains valid throughout the warm boot sequence. Currently the only attribute supported is non-volatile handles and pages, indicate by the least significant bit. 52h/00h -- Get Handle Attribute [19/0] On call: AH = 52h AL = 00h DX = handle On return: AH = error status AL = handle attribute Error Status: 00h, 80h, 81h, 83h, 84h, 8Fh, 91h 52h/01h -- Set Handle Attribute [19/1] On call: AH = 52h AL = 01h BL = new attribute value DX = handle On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Fh, 90h, 91h 52h/02h -- Get Handle Attribute Capability [19/2] On call: AH = 52h AL = 02h On return: AH = error status AL = attribute capability Error Status: 00h, 80h, 81h, 83h, 84h, 8Fh 53h -- Handle Name Functions [20] === EMS handles may have names associated with them. Each name can be any eight characters. Functions 53h and 54h provide a way of setting and interrogating the names associated with a particular handle. Function 53h manipulates names by number. A name of eight nulls is special, and indicates a handle has no name. Note, by the way, that nulls have no special significance, and they can appear in the middle of the name. In short, the handle name is 64 bits of binary information so far as the expanded memory manager is concerned. The author recommends that when defining a handle name that the selected name be padded on the right with spaces, ASCII graphic characters be used, and that control codes and hi-bit-set characters be avoided to make a debugger's life easier. 53h/00h -- Get Handle Name [20/0] On call: AH = 53h AL = 00h DX = handle DI = offset to eight byte target ES = segment selector of eight byte target On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Fh 53h/01h -- Set Handle Name [20/1] On call: AH = 53h AL = 01h DX = handle SI = offset to eight byte source DS = segment selector to eight byte source On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Fh, A1h 54h -- Handle Directory Functions [21] === Function 54h manipulates handles by name. 54h/00h -- Get Handle Directory [21/0] On call: AH = 54h AL = 00h DI = offset to 2550 byte target array ES = segment selector to 2550 byte target array On return: AH = error status AL = number of active handles Error Status: 00h, 80h, 81h, 84h, 8Fh The name array consists of 10 byte entries; each entry has a word containing the handle number, followed by the eight byte (64 bit) name. 54h/01h -- Search for Named Handle [21/1] On call: AH = 54h AL = 01h SI = offset to 8 byte array with name DS = segment selector to 8 byte array On return: AH = error status DX = handle [number] Error Status: 00h, 80h, 81h, 84h, 8Fh, A0h, A1h 54h/02h -- Get Total Handles [21/2] On call: AH = 54h AL = 02h On return: AH = error status BX = maximum number of handles Error Status: 00h, 80h, 81h, 84h, 8Fh This is NOT the current number of handles defined, but the maximum number of handles that can be supported in the current environment. 55h -- Alter Page Map and Jump (cross page branch) [22] === On call: AH = 55h AL = 00h (by physical page) or 01h (by seg#) DX = handle SI = offset to jump target and mapping table DS = segment selector for target/map table On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ah, 8Bh, 8Fh Flags and all registers except AX are preserved across the jump. One of the problems plaguing programmers in paged systems is being able to place code in paged memory. This function allows for an unstructured branch from code in one bank to code in potentially another bank without defining a bank manager in conventional memory. Thus several applications do not have to duplicate code. Note that code should follow the call to handle any error conditions that may arise. The programmer SHOULD NOT ASSUME the jump will always work. Graceful crashes are always preferable to sloppy ones... 56h -- Alter Page Map and Call (cross page call) [23/0][23/1] === On call: AH = 56h AL = 00h (by physical page) or 01h (by seg#) DX = handle SI = offset to jump target and mapping table DS = segment selector for target/map table On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ah, 8Bh, 8Fh Flags and all registers except AX are preserved to the called routine. On return, flags and all registers except AX are preserved; AL is set to zero and AX is undefined. One common calling convention is useless with this function: indicating an error by incrementing the return address before issuing a RET instruction. Obviously the return address is within the expanded memory manager, and if you increment the address "the results are undefined" to quote an ANSI language standards document. "Sloppy crash" is probably more accurate. PROBLEM: AX is not preserved on the return leg of the call. This is a particular pain to C and PASCAL programmers since the most common way to return integer values is in AX. The amount of stack space required by the function call cannot be determined at compile time. It CAN be determined at run time, using function 56h/02h, so at least the parameter frame can be located. Unfortunately this plays hob with using BP for both parameters and local storage. The best thing is to define a series of assembler wrapper routines that (1) copies the parameter stack to the new function and (2) preserves AX on return. This means redesigning functions to pass structures and the size of structures instead of individual parameters, a performance problem. 56h/02h -- Get Page Map Stack Space Size [23/2] On call: AH = 56h AL = 02h On return: AH = error status BX = number of bytes of stack used per call Error Status: 00h, 80h, 81h, 84h, 8Fh The author assumes the value returned in BX is even, to match the requirements of the 80x86 architecture. Implementers should check to be sure they follow this important guideline. 57h -- Memory Manipulation [24] === The request block is a structure with the following format: doubleword: region length in bytes byte: 0=source in conventional; 1=source in expanded word: source handle word: source offset in page or selector word: source logical page (exp.) or selector (conv.) byte: 0=target in conventional; 1=target in expanded word: target handle word: target offset in page or selector word: target logical page (exp.) or selector (conv.) Expanded memory allocated to a handle is considered to be a linear array, starting from logical page 0 and progressing through logical page 1, 2, ... n, n+1, ... up to the last logical page in the handle. 57h/00h -- Move Memory Region [24/0] On call: AH = 57h AL = 00h SI = offset to request block DS = segment selector to request block On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ah, 8Fh, 92h, 93h, 94h, 95h, 96h, 98h, A2h Moves data between two memory areas. Includes moves between paged and non-pages areas, or between two different paged areas. 57h/01h -- Exchange Memory Region [24/1] On call: AH = 57h AL = 01h SI = offset to request block DS = segment selector to request block On return: AH = error status Error Status: 00h, 80h, 81h, 83h, 84h, 8Ah, 8Fh, 93h, 94h, 95h, 96h, 97h, 98h, A2h Exchanges data between two memory areas. Includes exchanges between paged and non-pages areas, or between two different paged areas. 58h -- Mappable Physical Address Array [25] === These functions let you obtain a complete map of the way physical memory is laid out in a vendor independent manner. This is a functional equivalent of EEMS function 68h ("function 41"). EEMS function 60h ("function 33") is a subset call of 68h. 58h/00h -- Get Array [25/0] On call: AH = 58h AL = 00h DI = offset to target array ES = segment selector to target array On return: AH = error status CX = entries in target array Error Status: 00h, 80h, 81h, 84h, 8Fh The information returned is in an array composed of word pairs. The first word is the physical page's segment selector, the second word the physical page number. Note that values are not necessarily returned in a particular order, either ascending/decending segment selector values or as ascending/decending physical page number. For compatibility with earlier EMS specifications, physical page zero contains the segment selector value returned by function 41h, and physical pages 1, 2 and 3 return segment selector values that corrospond to the physical 16 KB blocks immediately following physical page zero. 58h/01h -- Get Array Entries [25/1] On call: AH = 58h AL = 01h On return: AH = error status CX = number of entries returned by 58h/00h Error Status: 00h, 80h, 81h, 84h, 8Fh Multiply CX by 4 for the byte count. 59h -- Hardware Information [26] === These functions return information specific to a given hardware implementation and to use of raw pages as opposed to standard pages. The intent is that only operating system code ever need use these functions. 59h/00h -- Get EMS Hardware Info [26/0] On call: AH = 59h AL = 00h DI = offset of target array (10 bytes) ES = segment selector of target array On return: AH = error status Error Status: 00h, 80h, 81h, 84h, 8Fh, A4h The target array has the following format: word: raw page size in paragraphs (multiples of 16 bytes) word: number of alternate register sets word: size of page maps (function 4Eh [15]) word: number of alternate registers sets for DMA word: DMA operation -- see full specification 59h/01h -- Get Unallocated Raw Page Count [26/1] On call: AH = 59h AL = 01h On return: AH = error status BX = unallocated raw pages DX = total raw pages Error Status: 00h, 80h, 81h, 84h, 8Fh 5Ah -- Allocate Raw Pages [27] === On call: AH = 5Ah BX = raw page count On return: AH = error status DX = handle Error Status: 00h, 80h, 81h, 84h, 85h, 87h, 88h It is intended this call be used only by operating systems. 5Bh -- Alternate Map Register Set [28] === Some boards support multiple sets of mapping registers, some for the specific purpose of performing DMA. These functions access the special features if they are available. It is intended these functions be used only by an operating system. This set of functions performs the same functions at EEMS function 6Ah subfunctions 04h and 05h ("function 43"). In the interests of brevity, the calls are not detailed here. For more information, please refer to the base document. 5Bh/00h -- Get Alternate Map Register Set [28/0] 5Bh/01h -- Set Alternate Map Register Set [28/1] 5Bh/02h -- Get Alternate Map Save Array Size [28/2] 5Bh/03h -- Allocate Alternate Map Register Set [28/3] 5Bh/04h -- Deallocate Alternate Map Register Set [28/4] 5Bh/05h -- Allocate DMA Register Set [28/5] 5Bh/06h -- Enable DMA on Alternate Map Register Set [28/6] 5Bh/07h -- Disable DMA on Alternate Map Register Set [28/7] 5Bh/08h -- Deallocate DMA Register Set [28/8] 5Ch -- Prepare EMS Hardware for Warm Boot [29] === On call: AH = 5Ch On return: AH = error status Error Status: 00h, 80h, 81h, 84h Provided for those hardware implementations that must be set up to preserve contents across a warm boot. 5Dh -- Operating System / Environment function control [30] === Security feature for operating systems and operating environment use. For brevity, the calls are not detailed here. 5Dh/00h -- Enable OS/E Function Set [30/0] 5Dh/01h -- Disable OS/E Function Set [30/1] 5Dh/02h -- Return OS/E Access Key [30/2] 61h -- Generic Accelerator Card Support [34] === For more information, contact AST Research for a copy of the _Generic Accelerator Card Driver (GACD) Specification_. ERROR RETURNS ------------- 00h -- Successful Completion 80h -- Software Error 81h -- Hardware Error 82h -- EMM busy (dropped in E/EMS 3.2) 83h -- Unknown EMM handle. 84h -- Unknown function code in AH. 85h -- All EMM handles are in use. 86h -- Page save/restore context error. 87h -- More pages requested than exist. 88h -- Not enough free pages to satisfy allocation request. 89h -- Zero page allocate request (dropped in EMS 4.0) 8Ah -- Logical page out of range 8Bh -- Physical page out of range 8Ch -- No room in the map context save area 8Dh -- Page context already saved 8Eh -- No page context to restore 8Fh -- Unknown sub-function 90h -- Attribute type undefined (new) 91h -- Warm boot data save not implemented (new) 92h -- Move overlaps memory (new) 93h -- Move/exchange larger than allocated region (new) 94h -- Conventional/expanded regions overlap (new) 95h -- Logical page offset outside of logical page (new) 96h -- Region larger than 1 MB. (new) 97h -- exchange source/destination overlap (new) 98h -- source/destination undefined or not supported (new) 99h -- (no status assigned) 9Ah -- Alt. Map Reg. Sets supported, specified set is not (new) 9Bh -- All alternate map & DMA registers sets allocated (new) 9Ch -- Alternate Map & DMA register sets not supported (new) 9Dh -- Alt Map Reg or DMA set no defined, allocated or is currently defined set (new) 9Eh -- Dedicated DMA channels not supported (new) 9Fh -- Dedicated DMA channels supported; specifed channel is not (new) A0h -- Named handle could not be found (new) A1h -- Handle Name already exists (new) A2h -- Move/exchange wraps around 1 MB boundry (new) A3h -- Data structure contains corrupted data (new) A4h -- Access denied (new)